home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / x2ftp / msdos / fg / fgl402b / manuals.arj / USER16.DOC < prev    next >
Text File  |  1995-02-06  |  8KB  |  204 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6. Chapter 16
  7.  
  8.  
  9.  
  10.  
  11.  
  12. Program Timing                                                                 
  13. 344   Fastgraph User's Guide
  14.  
  15.  
  16. Overview
  17.  
  18.      It is occasionally necessary to delay a program's execution for a brief
  19. period, or to determine how long it takes to execute specific sections of a
  20. program. Fastgraph includes routines to accomplish these tasks. Some of these
  21. routines are said to be real-time, which means they are independent of a
  22. system's processor speed, while the speed of others is processor-specific.
  23. This chapter describes both classes of timing routines, all of which are
  24. independent of the other parts of Fastgraph.
  25.  
  26.  
  27. Real-Time Routines
  28.  
  29.      Real-time operations center around the BIOS time-of-day clock, which is
  30. nothing more than a counter that the system automatically increments 18.2
  31. times per second. This number is often called the clock tick interrupt rate
  32. because an interrupt routine performs the incrementing. In addition, each
  33. increment is usually called a clock tick.
  34.  
  35.      The Fastgraph routine fg_waitfor delays a program's execution by the
  36. number of clock ticks specified as its argument. Because fg_waitfor uses clock
  37. ticks, the actual length of the delay is the same, regardless of the system's
  38. processor speed. Even when Fastgraph's asynchronous sound routines quadruple
  39. the clock tick interrupt rate, Fastgraph compensates for this internally so
  40. fg_waitfor always works as though the actual rate were still 18.2 times per
  41. second.
  42.  
  43.      Example 16-1 displays a message every five seconds that states how long
  44. the program has been running. The fg_waitfor routine produces the five-second
  45. delay by pausing 91 (18.2 times 5) clock ticks before the program displays
  46. each message. The program returns to DOS when you press any key.
  47.  
  48.                                  Example 16-1.
  49.  
  50.               #include <fastgraf.h>
  51.               #include <stdio.h>
  52.               void main(void);
  53.  
  54.               void main()
  55.               {
  56.                  unsigned int seconds;
  57.                  unsigned char key, aux;
  58.  
  59.                  fg_initpm();
  60.                  seconds = 0;
  61.                  do {
  62.                     fg_waitfor(91);
  63.                     seconds += 5;
  64.                     printf("%u seconds have elapsed.\n",seconds);
  65.                     fg_intkey(&key,&aux);
  66.                  }
  67.                  while (key+aux == 0);
  68.               }                                                                
  69.                                              Chapter 16:  Program Timing   345
  70.  
  71.      Another common application of fg_waitfor is to slow down a loop that uses
  72. fg_intkey to check for keystrokes. In loops that do little else, we may call
  73. fg_intkey too rapidly without this delay, and it is then possible that the
  74. BIOS may not be able to store characters in its keyboard buffer fast enough. A
  75. small delay, even one clock tick, often helps such "tight" loops.
  76.  
  77.      The fg_getclock routine provides an efficient way to measure time,
  78. especially differences in time. This routine has no arguments and returns a
  79. 32-bit unsigned integer (as its function value) representing the number of
  80. clock ticks since midnight. Example 16-2 demonstrates fg_getclock. In response
  81. to any keystroke (except Escape, which returns control to DOS), the program
  82. displays the number of clock ticks since midnight, and the number of ticks
  83. since the program started.
  84.  
  85.                                  Example 16-2.
  86.  
  87.       #include <fastgraf.h>
  88.       #include <stdio.h>
  89.       void main(void);
  90.  
  91.       #define ESC 27
  92.  
  93.       void main()
  94.       {
  95.          unsigned long start, ticks;
  96.          unsigned char key, aux;
  97.  
  98.          fg_initpm();
  99.          start = fg_getclock();
  100.          do {
  101.             ticks = fg_getclock();
  102.             printf("%lu ticks since midnight.\n",ticks);
  103.             printf("%lu ticks since start of program.\n\n",ticks-start);
  104.             fg_getkey(&key,&aux);
  105.          }
  106.          while (key != ESC);
  107.       }
  108.  
  109.  
  110.  
  111. Routines Dependent on the System Speed
  112.  
  113.      The fg_waitfor routine described in the previous section is independent
  114. of the system's processor speed. This means the actual length of its delay is
  115. the same on any system. Another routine, fg_stall, is similar to fg_waitfor,
  116. but its delay is proportional to the processor speed. Like fg_waitfor,
  117. fg_stall has a single integer argument that specifies the length of the delay.
  118. However, instead of being expressed in clock ticks, fg_stall measures the
  119. delay in delay units. The fg_stall routine treats the length as an unsigned
  120. quantity, so in 16-bit modes the maximum number of delay units we can specify
  121. is 65,535. The following table lists the approximate number of delay units per
  122. clock tick on three typical systems.                                           
  123. 346   Fastgraph User's Guide
  124.  
  125.                       system       delay units
  126.                        type      per clock tick
  127.  
  128.                    Tandy 1000 HX       280
  129.                    25 MHz 80386       3,400
  130.                    40 MHz 80386       7,100
  131.  
  132.      Fastgraph includes a routine that determines the number of delay units
  133. per clock tick for the processor being used. This is the fg_measure routine,
  134. which has no arguments and returns the number of delay units per clock tick as
  135. its function value. Once we determine this value, we can use fg_stall to delay
  136. a program's execution in real time. This provides a much more refined delay
  137. than the clock tick unit used by fg_waitfor.
  138.  
  139.      Example 16-3 is functionally identical to example 16-1, but it uses
  140. fg_stall instead of fg_waitfor to delay the program execution. The program
  141. first calls fg_measure to determine number of delay units equivalent to one
  142. clock tick. It then passes this value to fg_stall, called 91 times inside the
  143. for loop to create the five-second delay (because 91 clock ticks equals five
  144. seconds). The program returns to DOS when you press any key.
  145.  
  146.                                  Example 16-3.
  147.  
  148.               #include <fastgraf.h>
  149.               #include <stdio.h>
  150.               void main(void);
  151.  
  152.               void main()
  153.               {
  154.                  int i;
  155.                  int units_per_tick;
  156.                  unsigned int seconds;
  157.                  unsigned char key, aux;
  158.  
  159.                  fg_initpm();
  160.                  seconds = 0;
  161.                  printf("Benchmarking system speed...\n");
  162.                  units_per_tick = fg_measure();
  163.                  printf("Benchmark completed.\n\n");
  164.  
  165.                  do {
  166.                     for (i = 0; i < 91; i++)
  167.                        fg_stall(units_per_tick);
  168.                     seconds += 5;
  169.                     printf("%u seconds have elapsed.\n",seconds);
  170.                     fg_intkey(&key,&aux);
  171.                  }
  172.                  while (key+aux == 0);
  173.               }
  174.  
  175.  
  176.      One final point: fg_measure takes a few seconds to benchmark the system
  177. speed accurately. For this reason, you should only call fg_measure once
  178. (typically at the beginning of the program) and use its return value instead
  179. of calling fg_measure throughout the program.                                  
  180.                                              Chapter 16:  Program Timing   347
  181.  
  182.  
  183. Summary of Timing Routines
  184.  
  185.      This section summarizes the functional descriptions of the Fastgraph
  186. routines presented in this chapter. More detailed information about these
  187. routines, including their arguments and return values, may be found in the
  188. Fastgraph Reference Manual.
  189.  
  190.      FG_GETCLOCK returns the number of clock ticks since midnight as its
  191. function value. This quantity is a 32-bit unsigned integer.
  192.  
  193.      FG_MEASURE returns the approximate number of delay units per clock tick
  194. as its function value. This quantity is proportional to the system's processor
  195. speed.
  196.  
  197.      FG_STALL delays a program's execution for a given number of processor-
  198. specific delay units.
  199.  
  200.      FG_WAITFOR delays a program's execution for a given number of clock
  201. ticks. There are 18.2 clock ticks per second, regardless of the system's
  202. processor speed.                                                               
  203. 348   Fastgraph User's Guide
  204.